<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Flow of Control -->
<!-- All of the error stuff has been omitted for the time being, since it -->
<!-- is pretty variable.  Fix it up later. -->
<div class='chapter'>4. Flow of Control</div><p class='cindent'><!-- control structure -->
<p class='cindent'><!-- flow of control -->
	Lisp provides a variety of structures for flow of control.

	Function application is the basic method for construction of
programs.  Operations are written as the application of a function
to its arguments.  Usually, Lisp programs are written as a large collection
of small functions, each of which implements a simple operation.
These functions operate by calling one another, and so larger
operations are defined in terms of smaller ones.

<p class='cindent'><!-- "recursion" -->
	A function may always call itself in Lisp.  The calling of
a function by itself is known as <font class="italic">recursion</font>; it is analogous
to mathematical induction.

<p class='cindent'><!-- "iteration" -->
	The performing of an action repeatedly (usually with some
changes between repetitions) is called <font class="italic">iteration</font>, and is provided
as a basic control structure in most languages.  The <font class="italic">do</font> statement
of PL/I, the <font class="italic">for</font> statement of ALGOL/60, and so on are examples
of iteration primitives.  Lisp provides a general iteration facility
called <font class="lisp">do</font>, which is explained below.

<p class='cindent'><!-- "conditional" -->
	A <font class="italic">conditional</font> construct is one which allows a program
to make a decision, and do one thing or another based on some logical
condition.  Lisp provides <font class="lisp">and</font> and <font class="lisp">or</font>, which are simple
conditionals, and <font class="lisp">cond</font>, which is a more general conditional.

<p class='cindent'><!-- "non-local exit" -->
<p class='cindent'><!-- "exits" -->
	Non-local exits are similar to the <font class="italic">leave</font>, <font class="italic">exit</font>, and
<font class="italic">escape</font> constructs in many modern languages.
'c French, Italian, ...
They are similar to
a <font class="italic">return</font>, but are more general.  In Lisp, their scope is
determined at run-time.  They are implemented as the <font class="lisp">catch</font> and
<font class="lisp">*throw</font> functions.

	Lisp Machine Lisp also provides a multiple-process or coroutine capability.
This is explained in the section on <font class="italic">stack-groups</font> (<a href='fd_sg.html#stack-group'>this link</a>).

<div class='section'>4.1 Conditionals</div>
<div class="defspec"><font class='exdent'><font class='funcname'>and</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(and <font class="italic">form1 form2</font> ... )</font> evaluates the <font class="italic">form</font>s one at a time,
from left to right.  If any <font class="italic">form</font> evaluates to <font class="lisp">nil</font>, <font class="lisp">and</font>
immediately returns <font class="lisp">nil</font> without evaluating the remaining
<font class="italic">forms</font>.  If all the <font class="italic">forms</font> evaluate non-<font class="lisp">nil</font>, <font class="lisp">and</font> returns
the value of the last <font class="italic">form</font>.  <font class="lisp">and</font> can be used both for logical operations,
where <font class="lisp">nil</font> stands for <font class="italic">False</font> and <font class="lisp">t</font> stands for <font class="italic">True</font>, and as a
conditional expression. 
<pre class="lisp">
<font class='exdent'>Examples:</font><!-- exdent -->
(and x y)

(and (setq temp (assq x y))
     (rplacd temp z))

(and (not error-p)
     (princ "There was no error."))
</pre>
Note: <font class="lisp">(and) =&gt; t</font>, which is the identity for this operation.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>or</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(or <font class="italic">form1 form2</font> ...)</font> evaluates the <font class="italic">form</font>s one by one from left to right.
If a <font class="italic">form</font> evaluates to <font class="lisp">nil</font>, <font class="lisp">or</font> proceeds to evaluate the
next <font class="italic">form</font>.  If there are no more <font class="italic">form</font>s, <font class="lisp">or</font> returns <font class="lisp">nil</font>.
But if a <font class="italic">form</font> evaluates non-<font class="lisp">nil</font>, <font class="lisp">or</font> immediately returns
that value without evaluating any remaining <font class="italic">form</font>s.  <font class="lisp">or</font> can
be used both for logical operations, where <font class="lisp">nil</font> stands for False
and <font class="lisp">t</font> for True, and as a conditional expression.

Note:  <font class="lisp">(or) =&gt; nil</font>, the identity for this operation.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>cond</font><font class="italic"> Special Form</font></font><br>
The <font class="lisp">cond</font> special form consists of the symbol <font class="lisp">cond</font> followed by
several <font class="italic">clauses</font>.  Each clause consists of a <font class="italic">predicate</font> followed
by zero or more <font class="italic">forms</font>.  Sometimes the predicate is called the
<font class="italic">antecedent</font> and the forms are called the <font class="italic">consequents</font>. 

<pre class="lisp">
(cond (<font class="italic">antecedent consequent consequent</font>...)
      (<font class="italic">antecedent</font>)
      (<font class="italic">antecedent consequent</font> ...)
      ... )
</pre>

The idea is that each clause represents a case which
is selected if its antecedent is satisfied and the antecedents
of all preceding clauses were not satisfied.  When a clause
is selected, its consequent forms are evaluated.

<font class="lisp">cond</font> processes its clauses in order from left to right.  First,
the antecedent of the current clause is evaluated.  If the result is
<font class="lisp">nil</font>, <font class="lisp">cond</font> advances to the next clause.  Otherwise, the cdr of
the clause is treated as a list of forms, or consequents, which are
evaluated in order from left to right.  After evaluating the
consequents, <font class="lisp">cond</font> returns without inspecting any remaining
clauses.  The value of the <font class="lisp">cond</font> special form is the value of the
last consequent evaluated, or the value of the antecedent if there
were no consequents in the clause.  If <font class="lisp">cond</font> runs out of clauses,
that is, if every antecedent is <font class="lisp">nil</font>, that is, if no case is
selected, the value of the <font class="lisp">cond</font> is <font class="lisp">nil</font>. 
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
    (cond ((zerop x)    ;<font class="main">First clause:</font>
           (+ y 3))     ; (zerop x)<font class="main"> is the antecedent.</font>
                        ; (+ y 3)<font class="main"> is the consequent.</font>
          ((null y)     ;<font class="main">A clause with 2 consequents:</font>
           (setq y 4)   ;<font class="main"> this</font>
           (cons x z))  ;<font class="main"> and this.</font>
          (z)           ;<font class="main">A clause with no consequents:</font>
			;<font class="main"> the antecedent is just z.</font>
	  (t		;<font class="main">An antecedent of </font>t
	   105)		;<font class="main"> is always satisfied.</font>
       )		;<font class="main">This is the end of the cond.</font>
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='if'>if</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">if</font> allows a simple "if-then-else" conditional to
be expressed as <font class="lisp">(if <font class="italic">pred-form</font> <font class="italic">then-form</font> <font class="italic">else-form</font>)</font>.
<font class="lisp">if</font> is provided for stylistic reasons; some people think
it looks nicer than <font class="lisp">cond</font> for the simple case it handles.
<font class="lisp">(if <font class="italic">x y z</font>)</font> expands into <font class="lisp">(cond (<font class="italic">x</font> <font class="italic">y</font>) (t <font class="italic">z</font>))</font>.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='selectq'>selectq</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Many programs require <font class="lisp">cond</font> forms which check various
specific values of a form.
<pre class="lisp">
<font class="main">A typical example:</font>
(cond ((eq x 'foo) ...)
      ((eq x 'bar) ...)
      ((memq x '(baz quux mum)) ...)
      (t ...))
</pre>
The <font class="lisp">selectq</font> macro can be used for such tests.  
Its form is as follows:
<pre class="lisp">
(selectq <font class="italic">key-form</font>
	 (<font class="italic">pattern consequent consequent</font> ...)
	 (<font class="italic">pattern consequent consequent</font> ...)
	 (<font class="italic">pattern consequent consequent</font> ...)
	 ...)
</pre>
Its first "argument" is a form, which is evaluated (only once) as the
first thing <font class="lisp">selectq</font> does.  The resulting value is called the <font class="italic">key</font>.  It is
followed by any number of <font class="italic">clauses</font>.  The <font class="lisp">car</font> of each clause is
compared with the key, and if it matches, the consequents of this
clause are evaluated, and <font class="lisp">selectq</font> returns the value of the last
consequent.  If there are no matches, <font class="lisp">selectq</font> returns <font class="lisp">nil</font>.
Note that the patterns are <font class="italic">not</font> evaluated; if you want them to
be evaluated use <font class="lisp">select</font> rather than <font class="lisp">selectq</font>.
	A <font class="italic">pattern</font> may be any of:
.table 1 500 1500 0 80 1
.item 1) A symbol
If the <font class="italic">key</font> is <font class="lisp">eq</font> to the symbol, it matches.
.item 2) A number
If the <font class="italic">key</font> is <font class="lisp">eq</font> to the number, it matches.
Only small numbers (<font class="italic">fixnums</font>) will work.
.item 3) A list
If the <font class="italic">key</font> is <font class="lisp">eq</font> to one of the elements of the list,
then it matches.  The elements of the list should be symbols
or fixnums.
.item 4) <font class="lisp">t</font> or <font class="lisp">otherwise</font>
The symbols <font class="lisp">t</font> and <font class="lisp">otherwise</font> are special keywords which match anything.  
Either symbol may be used, it makes no difference.
<font class="lisp">t</font> is accepted for compatibility with Maclisp's <font class="lisp">caseq</font> construct.
.end_table
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(selectq x		;<font class="main">This is the same as the <font class="lisp">cond</font> example</font>
	 (foo ...)	;<font class="main"> above.</font>
	 (bar ...)
	 ((baz quux mum) ...)
	 (otherwise ...))
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='select'>select</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">select</font> is the same as <font class="lisp">selectq</font>, except that the elements of the
patterns are evaluated before they are used.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(select (frob x)
   (foo 1)
   ((bar baz) 2)
   (otherwise 3))
<font class="main">is equivalent to</font>
(let ((var (frob x)))
  (cond ((eq var foo) 1)
	((or (eq var bar) (eq var baz)) 2)
	(t 3)))
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='selector'>selector</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">selector</font> is the same as <font class="lisp">select</font>, except that you get to specify the function
used for the comparison instead of <font class="lisp">eq</font>.  For example,
<pre class="lisp">
(selector (frob x) equal
   (('(one . two)) (frob-one x))
   (('(three . four)) (frob-three x))
   (otherwise (frob-any x)))
</pre>
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='dispatch'>dispatch</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">(dispatch <font class="italic">byte-specifier</font> <font class="italic">n</font> <font class="italic">clauses...</font>)</font> is the same
as <font class="lisp">select</font> (not <font class="lisp">selectq</font>), but the key is obtained by evaluating
<font class="lisp">(ldb <font class="italic">byte-specifier n</font>)</font>.
'findex "ldb"
<font class="italic">byte-specifier</font> and <font class="italic">n</font> are both evaluated.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(princ (dispatch 0202 cat-type
	   (0 "Siamese.")
	   (1 "Persian.")
	   (2 "Alley.")
	   (3 (ferror nil
		      "~S is not a known cat type."
		      cat-type))))
</pre>
<!-- This example borrowed from DuMouchel.CatData -->
It is not necessary to include all possible values of the byte which
will be dispatched on.
[This function may get flushed.]
</div>

<div class='section'>4.2 Iteration</div><p class='cindent'><!-- "iteration" -->
<div class="defspec"><font class='exdent'><font class='funcname'>prog</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">prog</font> is a special form which provides temporary variables,
sequential evaluation of forms, and a "goto" facility.  A typical <font class="lisp">prog</font>
looks like:
<pre class="lisp">
(prog (<font class="italic">var1 var2</font> (<font class="italic">var3 init3</font>) <font class="italic">var4</font> (<font class="italic">var5 init5</font>))
 <font class="italic">tag1</font>
     <font class="italic">statement1</font>
     <font class="italic">statement2</font>
 <font class="italic">tag2</font>
     <font class="italic">statement2</font>
     . . .
    )
</pre>
<font class="italic">var1, var2, ...</font> are temporary variables.  When the <font class="lisp">prog</font> is entered, the
values of these variables are saved.  When the <font class="lisp">prog</font> is finished,
the saved values are restored.  The initial value of a variable inside
the <font class="lisp">prog</font> depends on whether the variable had an associated <font class="italic">init</font>
form or not; if it did, then the <font class="italic">init</font> form is evaluated and becomes
the initial value of the corresponding variable.  If there was no <font class="italic">init</font> form,
the variable is initialized to <font class="lisp">nil</font>.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(prog ((a t)  b  (c 5)  (d (car '(zz . pp))))
      <font class="italic">&lt;body&gt;</font>
      )
</pre>
The initial value of <font class="lisp">a</font> is <font class="lisp">t</font>, that of <font class="lisp">b</font> is <font class="lisp">nil</font>, that of <font class="lisp">c</font> is
the fixnum 5, and that of <font class="lisp">d</font> is the symbol <font class="lisp">zz</font>.
The binding and initialization of the variables is done in
<font class="italic">parallel</font>; that is,
all the initial values are computed before any of the variables are changed.

	The part of a <font class="lisp">prog</font> after the variable list is called the <font class="italic">body</font>.
An item in the body may be a symbol or a number, in which case it is called a
<font class="italic">tag</font>, or some other form (i.e. a list), in which case it is called a 
<font class="italic">statement</font>.

	After <font class="lisp">prog</font> binds the temporary variables, it processes each form
in its body sequentially.  <font class="italic">tags</font> are skipped over.  <font class="italic">Statements</font>
are evaluated, and their returned values discarded.  If the end of the body
is reached, the <font class="lisp">prog</font> returns <font class="lisp">nil</font>.  However, two special forms
may be used in <font class="lisp">prog</font> bodies to alter the flow of control.
If <font class="lisp">(return <font class="italic">x</font>)</font> is evaluated,
<font class="lisp">prog</font> stops processing its body, evaluates <font class="italic">x</font>, and returns the result.
If <font class="lisp">(go <font class="italic">tag</font>)</font> is evaluated, <font class="lisp">prog</font> jumps to the part of the body
labelled with the <font class="italic">tag</font>.  <font class="italic">tag</font> is not evaluated.
The "computed-<font class="lisp">go</font>" (mis)feature of Maclisp is not supported.

	The compiler requires that <font class="lisp">go</font> and <font class="lisp">return</font> forms be
<font class="italic">lexically</font> within the scope of the <font class="lisp">prog</font>; it is not possible for
one function to <font class="lisp">return</font> to a <font class="lisp">prog</font> which is in progress in its
caller.  This restriction happens not to be enforced in the interpreter.
Thus, a program which contains a <font class="lisp">go</font> which is not
contained within the body of a <font class="lisp">prog</font> (or a <font class="lisp">do</font>, see below)
cannot be compiled.  Since virtually all programs will be compiled
at some time, the restriction should be adhered to.

	Sometimes code which is lexically within more than one <font class="lisp">prog</font>
(or <font class="lisp">do</font>) form wants to <font class="lisp">return</font> from one of the outer <font class="lisp">prog</font>s.
However, the <font class="lisp">return</font> function normally returns from the innermost 
<font class="lisp">prog</font>.  In order to make <font class="lisp">return</font>ing from outer <font class="lisp">prog</font>s more
convenient, a <font class="lisp">prog</font> may be given a <font class="italic">name</font> by which it may be
referenced by a function called <font class="lisp">return-from</font>, which is similar to
<font class="lisp">return</font> but allows a particular <font class="lisp">prog</font> to be specified.
If the first subform of a <font class="lisp">prog</font> is a non-<font class="lisp">nil</font> symbol
(rather than a variable list), it is the name of the <font class="lisp">prog</font>.
See the description of the <font class="lisp">return-from</font> special form,
on (return-from-fun).
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(prog george (a b d)
      (prog (c b)
            ...
            (return-from george (cons b d))
            ...))
</pre>

	If the symbol <font class="lisp">t</font> is used as the name
of a <font class="lisp">prog</font>, then it will be made "invisible" to <font class="lisp">return</font>s;
<font class="lisp">return</font>s inside that <font class="lisp">prog</font> will return to the next outermost level
whose name is not <font class="lisp">t</font>.  <font class="lisp">(return-from t ...)</font> will return
from a <font class="lisp">prog</font> named <font class="lisp">t</font>.

See also the <font class="lisp">do</font> special form, which uses a body similar to
<font class="lisp">prog</font>. The <font class="lisp">do</font>, <font class="lisp">*catch</font>, and <font class="lisp">*throw</font> special forms are
included in Lisp Machine Lisp as an attempt to encourage goto-less programming
style, which often leads to more readable, more easily maintained code.  The
programmer is recommended to use these functions instead of <font class="lisp">prog</font>
wherever reasonable. 
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(prog (x y z)  ;x, y, z<font class="main"> are prog variables  - temporaries.</font>
   (setq y (car w) z (cdr w))     ;w<font class="main"> is a free variable.</font>
loop
   (cond ((null y) (return x))
         ((null z) (go err)))
rejoin
   (setq x (cons (cons (car y) (car z))
                 x))
   (setq y (cdr y)
         z (cdr z))
   (go loop)
err
   (break are-you-sure? t)
   (setq z y)
   (go rejoin))
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>prog*</font><font class="italic"> Special Form</font></font><br>
The <font class="lisp">prog*</font> special form is almost the same as <font class="lisp">prog</font>.  The only
difference is that the binding and initialization of the temporary
variables is done <font class="italic">sequentially</font>, so each one can depend on the
previous ones.  For example,
<pre class="lisp">
(prog ((y z) (x y)) (return x))
</pre>
returns the value of <font class="lisp">z</font>.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>do</font><font class="italic"> Special Form</font></font><br>
The <font class="lisp">do</font> special form provides a generalized iteration facility,
with an arbitrary number of "index variables" whose values are saved
when the <font class="lisp">do</font> is entered and restored when it is left, i.e. they are
bound by the <font class="lisp">do</font>.  The index variables are used in the iteration
performed by <font class="lisp">do</font>.  At the beginning, they are initialized to
specified values, and then at the end of each trip around the loop the
values of the index variables are changed according to specified
rules.  <font class="lisp">do</font> allows the programmer to specify a predicate which
determines when the iteration will terminate.  The value to be
returned as the result of the form may, optionally, be specified. 

<font class="lisp">do</font> comes in two varieties.

The newer variety of
<font class="lisp">do</font> looks like:
<pre class="lisp">
(do ((<font class="italic">var init repeat</font>)...)
    (<font class="italic">end-test exit-form</font>...)
    <font class="italic">body</font>...)
</pre>

The first item in the form is a list of zero or more index variable
specifiers.  Each index variable specifier is a list of the name of a
variable <font class="italic">var</font>, an initial value <font class="italic">init</font>, which defaults to <font class="lisp">nil</font>
if it is omitted, and a repeat value <font class="italic">repeat</font>.  If <font class="italic">repeat</font> is
omitted, the <font class="italic">var</font> is not changed between repetitions.

In index variable specifier can also be just the name of a variable.
In this case, the variable has an initial value of <font class="lisp">nil</font>, and is
not changed between repetitions.

All assignment to the index variables is done in parallel.  At the
beginning of the first iteration, all the <font class="italic">init</font>s are evaluated,
then the <font class="italic">var</font>s are saved, then the <font class="italic">var</font>s are <font class="italic">set</font> to the
values of the <font class="italic">init</font>s.  To put it another way, the <font class="italic">var</font>s are
<font class="lisp">lambda</font>-bound to the values of the <font class="italic">init</font>s.  Note that the
<font class="italic">init</font>s are evaluated <font class="italic">before</font> the <font class="italic">var</font>s are bound, i.e.
lexically <font class="italic">outside</font> of the <font class="lisp">do</font>.
At the beginning of each succeeding iteration those <font class="italic">var</font>s that have
<font class="italic">repeat</font>s get <font class="lisp">setq</font>'ed to the values of their respective
<font class="italic">repeat</font>s.  Note that all the <font class="italic">repeat</font>s are evaluated before any
of the <font class="italic">var</font>s is changed. 

The second element of the <font class="lisp">do</font>-form is a list of an end-testing
predicate <font class="italic">end-test</font>, and zero or more forms, called the
<font class="italic">exit-form</font>s.  At the beginning of each iteration, after processing
of the <font class="italic">repeat</font>s, the <font class="italic">end-test</font> is evaluated.  If the result is
<font class="lisp">nil</font>, execution proceeds with the body of the <font class="lisp">do</font>.  If the
result is not <font class="lisp">nil</font>, the <font class="italic">exit-forms</font> are evaluated from left to
right and then <font class="lisp">do</font> returns.  The value of the <font class="lisp">do</font> is the value
of the last <font class="italic">exit-form</font>, or <font class="lisp">nil</font> (<font class="italic">not</font> the value of the
<font class="italic">end-test</font> as you might expect) if there were no <font class="italic">exit-form</font>s. 
Note that the second element of the <font class="lisp">do</font>-form resembles a <font class="lisp">cond</font>
clause. 

If the second element of the form is <font class="lisp">nil</font>, there is no <font class="italic">end-test</font>
nor <font class="italic">exit-form</font>s, and the <font class="italic">body</font> of the <font class="lisp">do</font> is executed only
once.  In this type of <font class="lisp">do</font> it is an error to have <font class="italic">repeat</font>s. 
This type of <font class="lisp">do</font> is a "<font class="lisp">prog</font> with initial values."

If the second element of the form is <font class="lisp">(nil)</font>, the <font class="italic">end-test</font> is never
true and there are no <font class="italic">exit-form</font>s.  The <font class="italic">body</font> of the <font class="lisp">do</font>
is executed over and over. 
The infinite loop can be terminated by use of <font class="lisp">return</font> or <font class="lisp">*throw</font>.

The remainder of the <font class="lisp">do</font>-form constitutes a <font class="lisp">prog</font>-body; that is,
<font class="lisp">go</font>'s and <font class="lisp">return</font> forms are understood within the <font class="lisp">do</font> body,
as if it were a <font class="lisp">prog</font> body.  When the end of the body is reached,
the next iteration of the <font class="lisp">do</font> begins.  If a <font class="lisp">return</font> form is evaluated,
<font class="lisp">do</font> returns the indicated value and no more iterations occur. 

The older variety of <font class="lisp">do</font> is:
<pre class="lisp">
(do <font class="italic">var</font> <font class="italic">init</font> <font class="italic">repeat</font> <font class="italic">end-test</font> <font class="italic">body</font>...)
</pre>
The first time through the loop <font class="italic">var</font> gets the value of <font class="italic">init</font>; 
the remaining times through the loop it gets the value of <font class="italic">repeat</font>,
which is re-evaluated each time.  Note that <font class="italic">init</font> is evaluated
before the value of <font class="italic">var</font> is saved, i.e. lexically <font class="italic">outside</font> of the <font class="lisp">do</font>.
Each time around the loop, after <font class="italic">var</font> is set,
<font class="italic">end-test</font> is evaluated.  If it is non-<font class="lisp">nil</font>, the <font class="lisp">do</font> finishes
and returns <font class="lisp">nil</font>.  If the <font class="italic">end-test</font> evaluated to <font class="lisp">nil</font>, the <font class="italic">body</font> of
the loop is executed.  The <font class="italic">body</font> is like a <font class="lisp">prog</font> body.  <font class="lisp">go</font>
may be used.  If <font class="lisp">return</font> is used, its argument is the value of the
<font class="lisp">do</font>.  If the end of the <font class="lisp">prog</font> body is reached, another loop
begins. 

<pre class="lisp">
<font class='exdent'>Examples</font><!-- exdent -->
(setq n (array-length foo-array))
(do i 0 (1+ i) (= i n)
  (aset 0 foo-array i))		<font class="main">;zeroes out the array foo-array</font>

(do zz x (cdr zz) (or (null zz)
		      (zerop (f (car zz)))))
                   <font class="main">; this applies f to each element of x
                   ; continuously until f returns zero.
		   ; Note that the <font class="lisp">do</font> has no body.</font>

<font class="main"><font class="lisp">return</font> forms are often useful to do simple searches:</font>

(do i 0 (1+ i) (= i n)	<font class="main">; Iterate over the length of <font class="lisp">foo-array</font>.</font>
  (and (= (aref foo-array i) 5)	<font class="main">; If we find an element which
				;equals <font class="lisp">5</font>,</font>
       (return i)))	<font class="main">;  then return its index.</font>

</pre>
<pre class="lisp">
<font class='exdent'>Examples</font><!-- exdent -->
(do ((i 0 (1+ i))	<font class="main">; This is just the same as the above example,</font>
     (n (array-length foo-array)))
    ((= i n))		<font class="main">; but written as a new-style <font class="lisp">do</font>.</font>
  (aset 0 foo-array i))

(do ((z list (cdr z)) <font class="main">; z starts as <font class="lisp">list</font> and is <font class="italic">cdr</font>'ed each time.</font>
     (y other-list)   <font class="main">; y starts as <font class="lisp">other-list</font>, and is unchanged by the do.</font>
     (x))	      <font class="main">; x starts as <font class="lisp">nil</font> and is not changed by the <font class="lisp">do</font>.</font>
    (nil)	      <font class="main">; The end-test is <font class="lisp">nil</font>, so this is an infinite loop.</font>
  <font class="italic">body</font>)

(do ((x) (y) (z)) (nil) <font class="italic">body</font>)

<font class="main">is like</font>

(prog (x y z) <font class="italic">body</font>)
<font class="main">except that when it runs off the end of the <font class="italic">body</font>,
<font class="lisp">do</font> loops but <font class="lisp">prog</font> returns <font class="lisp">nil</font>.

On the other hand,</font>

     (do ((x) (y) (z)) nil <font class="italic">body</font>)

<font class="main">is identical to the <font class="lisp">prog</font> above (it does not loop.)</font>
</pre>

The construction
<pre class="lisp">
(do ((x e (cdr x))
     (oldx x x))
    ((null x))
  <font class="italic">body</font>)
</pre>
exploits parallel assignment to index variables.  On the first
iteration, the value of <font class="lisp">oldx</font> is whatever value <font class="lisp">x</font> had before
the <font class="lisp">do</font> was entered.  On succeeding iterations, <font class="lisp">oldx</font> contains
the value that <font class="lisp">x</font> had on the previous iteration. 

In either form of <font class="lisp">do</font>, the <font class="italic">body</font> may contain no forms at all.
Very often an iterative algorithm can be most clearly expressed entirely
in the <font class="italic">repeats</font> and <font class="italic">exit-forms</font> of a new-style <font class="lisp">do</font>,
and the <font class="italic">body</font> is empty.

<pre class="lisp">
(do ((x x (cdr x))
     (y y (cdr y))
     (z nil (cons (f x y) z))) ;<font class="main">exploits parallel</font>
    ((or (null x) (null y))    ;<font class="main"> assignment.</font>
     (nreverse z))             ;<font class="main">typical use of </font>nreverse.
    )                          ;<font class="main">no <font class="lisp">do</font>-body required.</font>

<font class="main">is like</font> (maplist 'f x y).
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>do-named</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">do-named</font> is just like <font class="lisp">do</font> except that its first subform
is a symbol, which is interpreted as the <font class="italic">name</font> of the <font class="lisp">do</font>.
The <font class="lisp">return-from</font> special form allows a <font class="lisp">return</font> from
a particular <font class="lisp">prog</font> or <font class="lisp">do-named</font> when several are nested.
See the description of such names in the explanation of the <font class="lisp">prog</font>
special form on (prog-fun), and that of <font class="lisp">return-from</font> on (return-from-fun).
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>dotimes</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">dotimes</font> is a convenient abbreviation for the most common integer iteration.
<font class="lisp">(dotimes (<font class="italic">index</font> <font class="italic">count</font>) <font class="italic">body...</font>)</font> performs <font class="italic">body</font>
the number of times given by the value of <font class="italic">count</font>, with <font class="italic">index</font> bound
to <font class="lisp">0</font>, <font class="lisp">1</font>, etc. on successive iterations.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(dotimes (i (// m n)
  (frob i))
<font class='exdent'>1is</font><!-- exdent -->
(do ((i 0 (1+ i))
     (count (// m n)))
    (( i count))
  (frob i))
<font class='exdent'>1except</font><!-- exdent -->
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>dolist</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">dolist</font> is a convenient abbreviation for the most common list iteration.
<font class="lisp">(dolist (<font class="italic">item</font> <font class="italic">list</font>) <font class="italic">body...</font>)</font> performs <font class="italic">body</font>
once for each element in the list which is the value of <font class="italic">list</font>, with
<font class="italic">item</font> bound to the successive elements.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(dolist (item (frobs foo))
  (mung item))
<font class='exdent'>1is</font><!-- exdent -->
(do ((lst (frobs foo) (cdr lst))
     (item))
    ((null lst))
  (setq item (car lst))
  (mung item))
<font class='exdent'>1except</font><!-- exdent -->
</pre>
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>go</font><font class="italic"> Special Form</font></font><br>
The <font class="lisp">(go <font class="italic">tag</font>)</font> special form is used to do a "go-to" within the
body of a <font class="lisp">do</font> or a <font class="lisp">prog</font>.  The <font class="italic">tag</font> must be a symbol.
It is not evaluated. <font class="lisp">go</font> transfers control to the point in the body labelled by a
tag <font class="lisp">eq</font> to the one given.  If there is no such tag in the body, the
bodies of lexically containing <font class="lisp">prog</font>s and <font class="lisp">do</font>s (if any) are examined as well.
If no tag is found, an error is signalled.
	Note that the <font class="lisp">go</font> form is a very special form: it does not ever
return a value.  A <font class="lisp">go</font> form may not appear as an argument to a regular
function, but only at the top level of a <font class="lisp">prog</font> or <font class="lisp">do</font>,
or within certain special forms such as conditionals which are within
a <font class="lisp">prog</font> or <font class="lisp">do</font>.
A <font class="lisp">go</font> as an argument to a regular function would be not only useless but
possibly meaningless.  The compiler does not bother to know how to compile it
correctly.  <font class="lisp">return</font> and <font class="lisp">*throw</font> are similar.
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(prog (x y z)
  (setq x <font class="italic">some frob</font>)
loop
  <font class="italic">do something</font>
  (and <font class="italic">some predicate</font> (go endtag))
  <font class="italic">do something more</font>
  (and (minusp x) (go loop))
endtag
  (return z))
</pre>
</div>

<div class='defun'><font class='exdent'><font class='funcname'>return <font class='italic' color='purple'>arg</font></font></font><br>
<font class="lisp">return</font> is used to return from a <font class="lisp">prog</font> or a <font class="lisp">do</font>.  The value
of <font class="lisp">return</font>'s argument is returned by <font class="lisp">prog</font> or <font class="lisp">do</font> as its
value.  In addition, <font class="lisp">break</font> recognizes the typed-in S-expression
<font class="lisp">(return <font class="italic">value</font>)</font> specially.  If this form is typed at a
<font class="lisp">break</font>, <font class="italic">value</font> will be evaluated and returned as the value of
<font class="lisp">break</font>.  If not at the top level of a form typed at a <font class="lisp">break</font>,
and not inside a <font class="lisp">prog</font> or <font class="lisp">do</font>, <font class="lisp">return</font> will cause an
error. 
<!-- Does our BREAK hack this yet? -->
<pre class="lisp">
<font class='exdent'>Example:</font><!-- exdent -->
(do ((x x (cdr x))
     (n 0 (* n 2)))
    ((null x) n)
 (cond ((atom (car x))
        (setq n (1+ n)))
       ((memq (caar x) '(sys boom bleah))
        (return n))))
</pre>
<font class="lisp">return</font> is, like <font class="lisp">go</font>, a special form which does not return a value.

<font class="lisp">return</font> can also be used to return multiple values from a <font class="lisp">prog</font> or
<font class="lisp">do</font>, by giving it multiple arguments.  For example,
<pre class="lisp">
(defun assqn (x table)
  (do ((l table (cdr l))
       (n 0 (1+ n)))
      ((null l) nil)
    (and (eq (caar l) x)
	 (return (car l) n))))
</pre>
This function is like <font class="lisp">assq</font>, but it returns an additional value
which is the index in the table of the entry it found.
See the special forms <font class="lisp">multiple-value</font> ((multiple-value-fun))
and <font class="lisp">multiple-value-list</font> ((multiple-value-list-fun)).
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>return-from</font><font class="italic"> Special Form</font></font><br>
A <font class="lisp">return-from</font> form looks like <font class="lisp">(return-from <font class="italic">name form1 form2 form3</font>)</font>.
The <font class="italic">form</font>s are evaluated sequentially, and then are returned
from the innermost containing <font class="lisp">prog</font> or <font class="lisp">do-named</font> whose name
is <font class="italic">name</font>.  See the description of <font class="lisp">prog</font> ((prog-fun)) in which
named <font class="lisp">prog</font>s and <font class="lisp">do</font>s are explained, and that of <font class="lisp">do-named</font> ((do-named-fun)).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>return-list <font class='italic' color='purple'>list</font></font></font><br>
<font class="italic">list</font> must not be <font class="lisp">nil</font>.  This function is like <font class="lisp">return</font> except
that the <font class="lisp">prog</font> returns all of the elements of <font class="italic">list</font>; if
<font class="italic">list</font> has more then one element, the <font class="lisp">prog</font> does a multiple-value
return.
<!-- What is this good for? -->
	To direct the returned values to a <font class="lisp">prog</font> or <font class="lisp">do-named</font> of a specific
name, use <font class="lisp">(return-from <font class="italic">name</font> (return-list <font class="italic">list</font>))</font>.
</div>

<div class="defspec"><font class='exdent'><font class='funcname'>multiple-value-return</font><font class="italic"> Special Form</font></font><br>
<font class="lisp">(multiple-value-return (<font class="italic">function</font> <font class="italic">arg1</font> <font class="italic">arg2</font> ...))</font>
applies the function to the arguments, and returns from the current <font class="lisp">prog</font> or <font class="lisp">do</font>
with the same values as <font class="italic">function</font> returns.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='defunp'>defunp</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Usually when a function uses <font class="lisp">prog</font>, the <font class="lisp">prog</font> form is
the entire body of the function; the definition of such a function
looks like <font class="lisp">(defun <font class="italic">name</font> <font class="italic">arglist</font> (prog <font class="italic">varlist</font> ...))</font>.
For convenience, the <font class="lisp">defunp</font> macro can be used to produce such definitions.
A <font class="lisp">defunp</font> form expands as follows:
<pre class="lisp">
(defunp fctn (args)
    form1
    form2
    ...
    formn)
</pre>
expands into
<pre class="lisp">
(defun fctn (args)
  (prog nil
	form1
	form2
	...
	(return formn)))
</pre>
</div>

<div class='section'>4.3 Non-local Exits</div><p class='cindent'><!-- "non-local exit" -->
<p class='cindent'><!-- catch -->
<p class='cindent'><!-- throw -->

<div class='defun'><font class='exdent'><font class='funcname'>*catch <font class='italic' color='purple'>tag form</font></font></font><br>
<font class="lisp">*catch</font> is the Lisp Machine Lisp function for doing structured
non-local exits.  <font class="lisp">(*catch <font class="italic">tag form</font>)</font> evaluates <font class="italic">form</font> and
returns its value, except that if, during the evaluation of <font class="italic">form</font>,
<font class="lisp">(*throw <font class="italic">tag y</font>)</font> should be evaluated, <font class="lisp">*catch</font> immediately returns
<font class="italic">y</font> without further evaluating <font class="italic">x</font>.  Note that the <font class="italic">form</font> argument
is <font class="italic">not</font> evaluated twice; the special action of <font class="lisp">*catch</font> happens
during the evaluation of its arguments, not during the execution of <font class="lisp">*catch</font>
itself.

The <font class="italic">tag</font>'s are used to match up <font class="lisp">*throw</font>'s with <font class="lisp">*catch</font>'s. 
<font class="lisp">(*catch 'foo <font class="italic">form</font>)</font> will catch a <font class="lisp">(*throw 'foo <font class="italic">form</font>)</font> but
not a <font class="lisp">(*throw 'bar <font class="italic">form</font>)</font>.  It is an error if <font class="lisp">*throw</font> is done
when there is no suitable <font class="lisp">*catch</font> (or <font class="lisp">catch-all</font>; see below). 

The values <font class="lisp">t</font> and <font class="lisp">nil</font> for <font class="italic">tag</font> are special and mean that all
throws are to be caught.  These are used by <font class="lisp">unwind-protect</font> and <font class="lisp">catch-all</font>
respectively.  The only difference between <font class="lisp">t</font> and <font class="lisp">nil</font> is in the
error checking; <font class="lisp">t</font> implies that after a "cleanup handler" is executed
control will be thrown again to the same tag, therefore it is an error if a specific
catch for this tag does not exist higher up in the stack.

<font class="lisp">*catch</font> returns up to four values; trailing null values are not
returned for reasons of microcode simplicity, however the values not
returned will default to <font class="lisp">nil</font> if they are received with the
<font class="lisp">multiple-value</font> special form.
If the catch completes normally,
the first value is the value of <font class="italic">form</font> and the second is <font class="lisp">nil</font>.
If a <font class="lisp">*throw</font> occurs, the first value is the second argument to
<font class="lisp">*throw</font>, and the second value is the first argument to <font class="lisp">*throw</font>,
the tag thrown to.  The third and fourth values are the third and fourth
arguments to <font class="lisp">*unwind-stack</font> if that was used in place of <font class="lisp">*throw</font>,
otherwise <font class="lisp">nil</font>.
To summarize, the four values returned by <font class="lisp">*catch</font> are the value,
the tag, the active-frame-count, and the action.
<pre class="lisp">
<font class='exdent'>Example</font><!-- exdent -->
(*catch 'negative
	(mapcar (function (lambda (x) 
                            (cond ((minusp x)
				   (*throw 'negative x))
				  (t (f x)) )))
               y)
     )
</pre>
which returns a list of <font class="lisp">f</font> of each element of <font class="lisp">y</font> if they are all
positive, otherwise the first negative member of <font class="lisp">y</font>. 

Note: The Lisp Machine Lisp functions <font class="lisp">*catch</font> and <font class="lisp">*throw</font> are
improved versions of the Maclisp functions <font class="lisp">catch</font> and <font class="lisp">throw</font>. 
The Maclisp ones are similar in purpose, but take their arguments in
reversed order, do not evaluate the <font class="italic">tag</font>, and may be used in an older form
in which no <font class="italic">tag</font> is supplied.  Compatibility macros are supplied so
that programs using the Maclisp functions will work.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>*throw <font class='italic' color='purple'>tag value</font></font></font><br>
<font class="lisp">*throw</font> is used with <font class="lisp">*catch</font> as a structured non-local exit mechanism.

<font class="lisp">(*throw <font class="italic">tag x</font>)</font> throws the value of <font class="italic">x</font> back to the most recent <font class="lisp">*catch</font>
labelled with <font class="italic">tag</font> or <font class="lisp">t</font> or <font class="lisp">nil</font>.  Other <font class="lisp">*catches</font> are skipped over.
Both <font class="italic">x</font> and <font class="italic">tag</font> are evaluated, unlike the Maclisp <font class="lisp">throw</font> function.

The values <font class="lisp">t</font> and <font class="lisp">nil</font> for <font class="italic">tag</font> are reserved.  <font class="lisp">nil</font> may not
be used, because it would cause an ambiguity in the returned values of <font class="lisp">*catch</font>.
<font class="lisp">t</font> invokes a special feature whereby the entire stack is unwound, and then
a coroutine transfer to the invoking stack-group is done.  During this process
<font class="lisp">unwind-protect</font>s receive control, but <font class="lisp">catch-all</font>s do not.  This feature
is provided for the benefit of system programs which want to completely unwind a stack.
It leaves the stack-group in a somewhat inconsistent state; it is best to
do a <font class="lisp">stack-group-preset</font> immediately afterwards.

See the description of <font class="lisp">*catch</font> for further details.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='catch'>catch</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br></div><div class='defmac'><font class='exdent'><font class='funcname' id='throw'>throw</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">catch</font> and <font class="lisp">throw</font> are provided only for Maclisp compatibility.
They expand as follows:
<pre class="lisp">
(catch <font class="italic">form</font> <font class="italic">tag</font>) ==&gt; (*catch (quote <font class="italic">tag</font>) <font class="italic">form</font>)
(throw <font class="italic">form</font> <font class="italic">tag</font>) ==&gt; (*throw (quote <font class="italic">tag</font>) <font class="italic">form</font>)
</pre>
The forms of <font class="lisp">catch</font> and <font class="lisp">throw</font> without tags are not supported.
</div>

<p class='cindent'><!-- unwinding a stack -->
<div class='defun'><font class='exdent'><font class='funcname'>*unwind-stack <font class='italic' color='purple'>tag value active-frame-count action</font></font></font><br>
This is a generalization of <font class="lisp">*throw</font> provided for program-manipulating
programs such as the error handler.

<font class="italic">tag</font> and <font class="italic">value</font> are the same as the corresponding arguments to
<font class="lisp">*throw</font>.

<font class="italic">active-frame-count</font>, if non-<font class="lisp">nil</font>, is the number of frames
to be unwound.  If this counts down to zero before a suitable <font class="lisp">*catch</font>
is found, the <font class="lisp">*unwind-stack</font> terminates and
<font class="italic">that frame</font> returns <font class="italic">value</font> to whoever called it.
This is similar to Maclisp's <font class="lisp">freturn</font> function.
'findex "freturn"

If <font class="italic">action</font> is non-<font class="lisp">nil</font>, whenever the <font class="lisp">*unwind-stack</font> would be
ready to terminate (either due to <font class="italic">active-frame-count</font> or due to
<font class="italic">tag</font> being caught as in <font class="lisp">*throw</font>), instead, a stack-group call is
forced to the previous stack-group, generally the error handler.  The
unwound stack-group is left in <font class="italic">awaiting-return</font> state, such that the
value returned when the stack-group is resumed will become the value
returned by the frame, (i.e. the <font class="italic">value</font> argument to
<font class="lisp">*unwind-stack</font> will be ignored in this case, and the value passed to
the stack group when it is resumed will be used instead.)

Note that if both <font class="italic">active-frame-count</font> and <font class="italic">action</font> are <font class="lisp">nil</font>,
<font class="lisp">*unwind-stack</font> is identical to <font class="lisp">*throw</font>.
</div>

<p class='cindent'><!-- unwind protection -->
<p class='cindent'><!-- cleanup handlers -->
<div class='defmac'><font class='exdent'><font class='funcname' id='unwind-protect'>unwind-protect</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>Sometimes it is necessary to evaluate a form and make sure that
certain side-effects take place after the form is evaluated;
a typical example is:
<pre class="lisp">
(progn
   (turn-on-water-faucet)
   (hairy-function 3 nil 'foo)
   (turn-off-water-faucet))
</pre>
The non-local exit facility of Lisp creates a situation in which
the above code won't work, however: if <font class="lisp">hairy-function</font> should
do a <font class="lisp">*throw</font> to a <font class="lisp">*catch</font> which is outside of the <font class="lisp">progn</font>
form, then <font class="lisp">(turn-off-water-faucet)</font> will never be evaluated
(and the faucet will presumably be left running).

In order to allow the above program to work, it can
be rewritten using <font class="lisp">unwind-protect</font> as follows:
<pre class="lisp">
(unwind-protect
  (progn (turn-on-water-faucet)
	 (hairy-function 3 nil 'foo))
  (turn-off-water-faucet))
</pre>
If <font class="lisp">hairy-function</font> does a <font class="lisp">*throw</font> which attempts to quit
out of the evaluation of the <font class="lisp">unwind-protect</font>, the
<font class="lisp">(turn-off-water-faucet)</font> form will be evaluated in between
the time of the <font class="lisp">*throw</font> and the time at which the <font class="lisp">*catch</font> returns.
If the <font class="lisp">progn</font> returns normally, then the <font class="lisp">(turn-off-water-faucet)</font>
is evaluated, and the <font class="lisp">unwind-protect</font> returns the result of the <font class="lisp">progn</font>.
One thing to note is that <font class="lisp">unwind-protect</font> cannot return multiple values.

The general form of <font class="lisp">unwind-protect</font> looks like
<pre class="lisp">
(unwind-protect <font class="italic">protected-form</font>
                <font class="italic">form1</font>
                <font class="italic">form2</font>
                ...)
</pre>
<font class="italic">protected-form</font> is evaluated, and when it returns or when it
attempts to quit out of the <font class="lisp">unwind-protect</font>, the <font class="italic">form</font>s
are evaluated.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='let-globally'>let-globally</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">let-globally</font> is similar in form to <font class="lisp">let</font> (see (let-fun)).
The difference is that <font class="lisp">let-globally</font> does not <font class="italic">bind</font> the
variables; instead, it <font class="italic">sets</font> them, and sets up an <font class="lisp">unwind-protect</font>
(see (unwind-protect-fun)) to set them back.  The important
difference between <font class="lisp">let-globally</font> and <font class="lisp">let</font> is that when
the current stack group (see <a href='fd_sg.html#stack-group'>this link</a>) cocalls some other stack
group, the old values of the variables are <font class="italic">not</font> restored.
</div>

<div class='defmac'><font class='exdent'><font class='funcname' id='catch-all'>catch-all</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br><font class="lisp">(catch-all <font class="italic">form</font>)</font> is like <font class="lisp">(*catch <font class="italic">some-tag form</font>)</font>
except that it will catch a
<font class="lisp">*throw</font> to any tag at all.  Since the tag thrown to
is the second returned value, the caller of <font class="lisp">catch-all</font> may continue 
throwing to that tag if he wants.  The one thing that <font class="lisp">catch-all</font>
will not catch is a <font class="lisp">*throw</font> to <font class="lisp">t</font>.
<font class="lisp">catch-all</font> is a macro which expands into <font class="lisp">*catch</font> with a <font class="italic">tag</font> of <font class="lisp">nil</font>.
</div>

<div class='section'>4.4 Mapping</div><p class='cindent'><!-- "mapping" -->

<div class='defun'><font class='exdent'><font class='funcname'>map <font class='italic' color='purple'>fcn &rest lists</font></font></font><br>
.defun1 mapc fcn &rest lists
.defun1 maplist fcn &rest lists
.defun1 mapcar fcn &rest lists
.defun1 mapcon fcn &rest lists
.defun1 mapcan fcn &rest lists

Mapping is a type of iteration in which a function is 
successively applied to pieces of a list.
There are several options for the way in which the pieces of the list are
chosen and for what is done with the results returned by the applications of
the function.

For example, <font class="lisp">mapcar</font> operates on successive <font class="italic">elements</font> of the list. 
As it goes down the list, it calls the function giving it an element
of the list as its one argument:  first the <font class="lisp">car</font>, then the
<font class="lisp">cadr</font>, then the <font class="lisp">caddr</font>, etc., continuing until the end of the
list is reached.  The value returned by <font class="lisp">mapcar</font> is a list of the
results of the successive calls to the function.  An example of the
use of <font class="lisp">mapcar</font> would be <font class="lisp">mapcar</font>'ing the function <font class="lisp">abs</font> over
the list <font class="lisp">(1 -2 -4.5 6.0e15 -4.2)</font>, which would be written as
<font class="lisp">(mapcar (function abs) '(1 -2 -4.5 6.0e15 -4.2))</font>.
The result is <font class="lisp">(1 2 4.5 6.0e15
4.2)</font>.  

In general, the mapping functions take any number of arguments.  For example,
<pre class="lisp">
(mapcar <font class="italic">f x1 x2 ... xn</font>)
</pre>
In this case <font class="italic">f</font> must be a function of <font class="italic">n</font> arguments.
<font class="lisp">mapcar</font> will proceed
down the lists <font class="italic">x1, x2, ..., xn</font> in parallel.
The first argument to <font class="italic">f</font> will
come from <font class="italic">x1</font>, the second from <font class="italic">x2</font>, etc.
The iteration stops as soon as
any of the lists is exhausted.

There are five other mapping functions besides <font class="lisp">mapcar</font>.  <font class="lisp">maplist</font>
is like <font class="lisp">mapcar</font> except that the function is applied to the list and
successive cdr's of that list rather than to successive elements of the
list.  <font class="lisp">map</font> and <font class="lisp">mapc</font> are like <font class="lisp">maplist</font> and <font class="lisp">mapcar</font>
respectively, except that they don't return any useful value.  These
functions are used when the function is being called merely for its
side-effects, rather than its returned values.  <font class="lisp">mapcan</font> and
<font class="lisp">mapcon</font> are like <font class="lisp">mapcar</font> and <font class="lisp">maplist</font> respectively, except
that they combine the results of the function using <font class="lisp">nconc</font> instead
of <font class="lisp">list</font>.  That is,
<pre class="lisp">
(defun mapcon (f x y)
    (apply 'nconc (maplist f x y)))
</pre>
Of course, this definition is less general than the real one.

Sometimes a <font class="lisp">do</font> or a straightforward recursion is preferable to a
map;  however, the mapping functions should be used wherever they
naturally apply because this increases the clarity of the code. 

Often <font class="italic">f</font> will be a lambda-expression, rather than a symbol;
for example,
<pre class="lisp">
(mapcar (function (lambda (x) (cons x something)))
	some-list)
</pre>

The functional argument to a mapping function must be acceptable
to <font class="lisp">apply</font> - it cannot be a macro or the name of a special form.
Of course, there is nothing wrong with using functions which have optional
and rest parameters.

.group
Here is a table showing the relations between
the six map functions.
.nofill
<font class="lispcode">
                              applies function to

                         |  successive  |   successive  |
                         |   sublists   |    elements   |
          ---------------+--------------+---------------+
              its own    |              |               | 
              second     |     map      |     mapc      |
             argument    |              |               |
          ---------------+--------------+---------------+
            list of the  |              |               |
returns      function    |    maplist   |    mapcar     |
              results    |              |               |
          ---------------+--------------+---------------+
            nconc of the |              |               |
              function   |    mapcon    |    mapcan     |
              results    |              |               |
          ---------------+--------------+---------------+</font>
.fill
	There are also functions (<font class="lisp">mapatoms</font> and <font class="lisp">mapatoms-all</font>)
for mapping over all symbols in certain
packages.  See the explanation of packages ((package)).
.apart
</div>
.eof
</body>
</html>

